
Basic Programming Guidelines 

Below is a set of basic guidelines for programming 
practices meant to insure that your programs are 

compatible across current and future machines. 

Developers are urged to strive for compatibility as much 
=s possible. While this list is not complete by any 
.eans, it will hopefully point you in the right direction. 

Re-read this section after you have become familiar with 
the documentation in the developers kit. You may not 
immediately understand the references and reasons 
behind the guidelines, but they will become clearer as 
you learn more about the system. 

1) Read all of the documentation included in the 
developers kit before starting to program. It's a lot of 
reading, but it will save you from making some hard 
to find mistakes later on down the road. 

2) Don't make assumptions about the screen. There 
will be new video modes in new machines and 
add-on video boards you didn't know about when 
you wrote your program. If you make assumptions 
about the display hardware, then your program will 
probably fail when something new comes along. 

i 

The operating system provides information about 
the display in use. This is accomplished by opening 
a GEM VDI Workstation and examining the returned 
information. Additional information is available 
through GEM VDI inquire functions. 

Some basic rules and some of the more common 
assumptions to avoid are given below. 

a) A certain screen resolution does not mean a 
certain number of colors on screen at once, or 
vice versa. 

b) Dont assume the color palette is a certain 
number of colors because you're on a certain 

type of machine. The machine may have an 
add-on video board which provides more colors. 


c) Many early programs written for the ST made 
assumptions about the screen resolution by 
looking at the hardware video shifter mode 

® through the GetrezO XBiOS function, which 

ultimately has nothing to do with the screen 
resolution. 

d) If the information is available from GEM VDI, then 
get it from GEM VDI, not someplace else, 
including Line-A. GEM VDI will always have the 
last word. 

The use of Line-A is strongly discouraged. 
Documentation is still provided in the developer's 
kit about Line-A, but it should be avoided rf at all 
possibla Most applications have no reason to 
use it Contact Atari developer technical support 
for more information if required. 

3) Dont assume only certain machines have certain 
hardware or software featu res. 

The Cookie Jar is an operating system feature that 
allows programs to obtain information about the 
system they are running on, such as if DMA stereo 
sound is available tt should be used wherever 
possible when a program needs to know if a certain 
hardware or software feature is available. Use the 
machine type ONLY for detecting features which 
dont have a cookie of their own. The Cookie Jar is 
discussed in the STE TOS Release Notea 

4) Learn how to program the G EM AES before you 
learn to program the GEM VDI. The heart of a GEM 
program lies in the menua windows, and dialogs 
through which the user must operate the program. 
These are all the responsibility of GEM AES. The 
sooner you learn to utilize GEM AES, the more 
polished and professional your programs will appear. 

• * • * , • 

Examples of existing applications which make good 
use of the GEM AES indude Migraph’s Touch-Up 
(with its pop-up menus and palettes), GribmVStrata's 
STaiker and STeno (all-around good examples). The 
Resource Construction Set (included with the 

developer's kit), and the GEM Desktop. 

• » • • # 

• * • 

If you would like an idea of how to do something and 
you cannot find an existing example, please contact 
Atari developer technical support- . 

* ■ * . . 
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5) Dont do something different just for the sake of 
being different. 

When in doubt about how something should work or 
look, examine how the GEM Desktop looks and how 


it does things, if your program has something similar, 10) Do not use or rely upon undocumented variables 
it should follow the example of the GEM Desktop. in memory or reserved variables or parameters 

in a function call or data structure.. They wfll 

When creating the user interface for your program, move or change when a new operating system 

keep in mind that simple is better. In almost'all cases, revision is introduced. 

the simpler something is, the easier it is to learn, and 

the easier it is to use. Don't make extra steps for the 

user if you can avoid it. 

6) Replacing, ignoring, or working around the 
resources of the operating system should be 
avoided. 

For example, there is a standard system file selector 
for a reason. A GEM program which doesn't use a 
standard file selector is inconsistent with the 
interface of standard applications. At least make it a 
user preference option in the application. 

As another example, some programs use a 
proprietary font format for their text capabilities, 
rather than us'ng GEM'S font and text functions. As 
a result, these programs did not work with the 
outline font capacities of FSMGDOS when it 
became available. On the other hand, many older 
programs which did use GEM'S font and text 
functions work just fine with FSMGDOS outline fonts. 

If a program wants to do something like support its 
own proprietary font format, it should be done in 
addition to supporting the standard GEM features, 
not instead of them. 

7) Be familiar with the various update documents such 
as the Rainbow TOS Release Notes and 
TT030 TOS Release Notes. These will contain 
additions, corrections, and clarifications to other 

documents in the developer's kit 
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8) Watch the ATARI.RSC developer newsletter for any 

documentation corrections or updates. . 

9) If you can use a vector to get a memory address, do 

it Don't assume that something will always be at the 

* „ 

same place in all machines and ail versions of the 
operating system unless it is a documented memory 
address. - 

• - - : 
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For example, the operating system itself is in a 
different place in newer machines than with older 
machines. If an application needs to access the OS 
header to get a version number or country code, for 
example, then the application should not assume 
that the OS ROM starts at a certain memory location. 

Instead, it should get the address of the OS header 
from the appropriate system variable. 




